/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 * 
 * Copyright (c) 2008-2009, The KiWi Project (http://www.kiwi-project.eu)
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without 
 * modification, are permitted provided that the following conditions are met:
 * - Redistributions of source code must retain the above copyright notice, 
 *   this list of conditions and the following disclaimer.
 * - Redistributions in binary form must reproduce the above copyright notice, 
 *   this list of conditions and the following disclaimer in the documentation 
 *   and/or other materials provided with the distribution.
 * - Neither the name of the KiWi Project nor the names of its contributors 
 *   may be used to endorse or promote products derived from this software 
 *   without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
 * POSSIBILITY OF SUCH DAMAGE.
 * 
 * Contributor(s):
 * 
 * 
 */
package kiwi.core.api.triplestore;

import kiwi.core.model.rdf.*;

import java.util.Set;

// ESCA-JAVA0136:
/**
 * @author Sebastian Schaffert
 *
 */
public interface TripleStore {
	






    // *****************************************************************************************************
    // methods for creating and removing triples
    // *****************************************************************************************************


    /**
     * Create or retrieve a KiWi triple in this knowledge space using the provided subject, predicate, and
     * object.
     * <p>
     * If a triple with the same subject/property/object already exists in the knowledge base,
     * it is returned.
     * <p>
     * If a triple with the same subject/property/object does not yet exist, this method will automatically
     * generate a new triple id for the triple, and then store the triple in
     * the knowledge base. The rationale behind this is that many methods of ExtendedTriple directly work on
     * the knowledge base and require both, a triple id and the triple to be persisted.
     *
     * @param subject
     * @param property
     * @param object
     * @param context
     */
    public KiWiTriple createTriple(KiWiResource subject, KiWiUriResource property, KiWiNode object, KiWiUriResource context);




	/**
	 * Remove a triple from the repository. This method only adds the triple to the
     * current transaction data; the triple will be persisted to the database and repository
     * on transaction commit. 
     * 
	 * @param triple
	 */
	public void removeTriple(KiWiTriple triple);


	/**
	 * Remove a triple from the repository with the given subject, property, and object
	 * @param subject
	 * @param property
	 * @param object
	 */
	public void removeTriple(KiWiResource subject, KiWiUriResource property, KiWiNode object, KiWiUriResource context);

	/**
    /**
     * Remove all triples matching the pattern passed in the parameters. Arguments that are passed as "null" are
     * considered wildcards like in listTriples, i.e. all values match. Inferred triples are not included.
     *
     * @param subject the subject of the triples to list or null for wildcard
     * @param property the property of the triples to list or null for wildcard
     * @param object the object of the triples to list or null for wildcard
     * @param context the context/knowledge space of the triples to list or null for all spaces
     */
    public void removeTriples(KiWiResource subject, KiWiUriResource property, KiWiNode object, KiWiUriResource context);


    /**
     * Add or update a triple to/in the triple store. This method only adds the triple to the
     * current transaction data; the triple will be persisted to the database and repository
     * on transaction commit.
     *
     * @param triple
     */
    public void storeTriple(KiWiTriple triple);

    // *****************************************************************************************************
    // methods for listing and querying triples
    // *****************************************************************************************************

    /**
     * Return the number of non-deleted triples currently contained in the triple store
     *
     * @return
     */
	public long size();

	/**
	 * List all triples contained in this Knowledge Space.
	 * @return
	 */
	public Set<KiWiTriple> listTriples(boolean inferred);



    /**
     * List all triples matching the subject, property, object, and context given as argument. Parameters that are null
     * are treated as wildcards, i.e. all values match. Inferred values are included.
     *
     * @param subject the subject of the triples to list or null for wildcard
     * @param property the property of the triples to list or null for wildcard
     * @param object the object of the triples to list or null for wildcard
     * @param context the context/knowledge space of the triples to list or null for all spaces
     * @return a List of triples matching the search criteria
     */
    public Set<KiWiTriple> listTriples(KiWiResource subject, KiWiUriResource property, KiWiNode object, KiWiUriResource context);

    /**
     * List all triples matching the subject, property, object, and context given as argument. Parameters that are null
     * are treated as wildcards, i.e. all values match. If the parameter inferred is true, inferred triples are included,
     * otherwise inferred triples are not included.
     *
     * @param subject the subject of the triples to list or null for wildcard
     * @param property the property of the triples to list or null for wildcard
     * @param object the object of the triples to list or null for wildcard
     * @param context the context/knowledge space of the triples to list or null for all spaces
     * @param inferred if true, inferred triples are included in the result; if false not
     * @return a List of triples matching the search criteria
     */
    public Set<KiWiTriple> listTriples(KiWiResource subject, KiWiUriResource property, KiWiNode object, KiWiUriResource context, boolean inferred);


    /**
     * List all triples matching the subject, property, object, and context given as argument. Parameters that are null
     * are treated as wildcards, i.e. all values match. If the parameter inferred is true, inferred triples are included,
     * otherwise inferred triples are not included.
     * <p/>
     * Note that paging with limit and offset is not reliable with transaction data.
     *
     * @param subject  the subject of the triples to list or null for wildcard
     * @param property the property of the triples to list or null for wildcard
     * @param object   the object of the triples to list or null for wildcard
     * @param context  the context/knowledge space of the triples to list or null for all spaces
     * @param inferred if true, inferred triples are included in the result; if false not
     * @param offset   paging: with which result to start
     * @param limit    paging: how many results to return maximally
     * @return a List of triples matching the search criteria
     */
    public Set<KiWiTriple> listTriples(KiWiResource subject, KiWiUriResource property, KiWiNode object, KiWiUriResource context, boolean inferred, int offset, int limit);



    public Set<KiWiTriple> listTriples(KiWiResource subject, KiWiUriResource property, KiWiNode object, Set<KiWiUriResource> contextSet, boolean inferred, int offset, int limit);

    /* List all triples matching the subject, property, object, and context given as argument. Parameters that are null
     * are treated as wildcards, i.e. all values match. If the parameter inferred is true, inferred triples are included,
     * otherwise inferred triples are not included.
     * <p/>
     * Note that paging with limit and offset is not reliable with transaction data.
     *
     * @param subject  the subject of the triples to list or null for wildcard
     * @param propertyPath a path of properties to use for connecting subject and object
     * @param object   the object of the triples to list or null for wildcard
     * @param context  the context/knowledge space of the triples to list or null for all spaces
     * @param inferred if true, inferred triples are included in the result; if false not
     * @param offset   paging: with which result to start
     * @param limit    paging: how many results to return maximally
     * @return a List of triples matching the search criteria
     */
    //public Set<KiWiTriple> listTriples(KiWiResource subject, KiWiUriResource[] propertyPath, KiWiNode object, KiWiUriResource context, boolean inferred, int offset, int limit);


    /**
     * Check whether the triple formed by the parameters exists.
     * @param subject
     * @param property
     * @param object
     * @return
     */
    public boolean hasTriple(KiWiResource subject, KiWiUriResource property, KiWiNode object);

    public boolean hasTriple(KiWiResource subject, KiWiUriResource property, KiWiNode object, KiWiUriResource context);


    // *****************************************************************************************************
    // methods for working with namespaces
    // *****************************************************************************************************


    /**
     * Return the URI of the namespace with the given prefix as string
     * @param prefix the prefix of the namespace
     * @return a string containing the URI of the namespace
     */
	public String getNamespaceUri(String prefix);

    /**
     * Return the prefix of the namespace with the given URI
     * @param uri the URI of the namespace
     * @return a string containing the current prefix of the namespace
     */
	public String getNamespacePrefix(String uri);


    /**
     * Return the KiWiNamespace object of the namespace that currently has the given prefix
     *
     * @param prefix the current prefix of the namespace
     * @return the KiWiNamespace object of the namespace of the given prefix
     */
	public KiWiNamespace getNamespaceByPrefix(String prefix);


    /**
     * Return the KiWiNamespace object of the namespace that has the given uri
     *
     * @param uri the uri of the namespace
     * @return the KiWiNamespace object of the namespace of the given uri
     */
    public KiWiNamespace getNamespaceByUri(String uri);



    /**
     * Add or update a namespace to/in the triple store. This method only adds the namespace to the
     * current transaction data; the namespace will be persisted to the database and repository
     * on transaction commit.
     *
     * @param prefix the prefix to use
     * @param uri the KiWi namespace object to update
     */
	public void setNamespace(String prefix, String uri);


	

	
	public void removeNamespace(String prefix);

	/**
	 * Removes a namespace from triplestore
	 * @param ns
	 */
	public void removeNamespace(KiWiNamespace ns);
	
	
	/**
	 * List all namespaces defined for the knowledge space
	 * @return
	 */
	public Iterable<KiWiNamespace> listNamespaces();

	public void clear();
	
	public void clearCaches();

}
